Create Payment Request

In this guide, we will create a payment request using Postman and the ApteanPay GraphQL Playground.

We can create a payment request in two ways,

  1. Payment Request With Invoice:
    APIs called:
  2. Payment Request Without Invoice:
    APIs called:

Headers Required for GraphQL API Playground

Theses are the mandatory headers required for ApteanPay Merchant API (GraphQL).

  {
    "x-aptean-apim":"<<<your product specific apim key here>>>",
    "x-aptean-tenant":"<<<your tenant id here>>>",
    "x-aptean-tenant-secret": "<<<your tenant secret here>>>"
  }

Please fill your respective values received during onboarding.

Upload

To upload an invoice in Postman application and perform the following steps.

  1. Open the Postman Application.

  2. Paste the Merchant API (GraphQL) url https://stg.api.apteanpay.com/.

  3. Select request mode as POST.

  4. Copy the following keys and fill the respective values.

    Key Value
    x-aptean-apim {your product specific apim key here}
    x-aptean-tenant {your tenant Id here}
    x-aptean-secret {your tenant secret here}

  5. Select Headers and paste the copied key-value pairs.

  6. Copy the following Key-Value Pairs.

    Key Value
    operations {"query": "mutation($file: Upload!){\n upload(input:{ file: $file}){\n uniqueId\n message\n code\n }\n}"}
    map {"0":["variables.file"] }
    0 {Select the file you want to upload}

    NOTE: In the third key-value pair the type should be file and in value you need to select the invoice file that you want to upload.

  7. Now Select Body and then select form-data as the body-type. Paste the copied Key-Value pairs in the form-data and Send the request.

  8. Once you get the response, copy the uniqueId value. This uniqueId is required to upsert payment request in the next step.

Upsert Payment Request

To upsert/create a new payment request, perform the following steps.

  1. Open your browser and enter the Merchant API (GraphQL) url from here.

  2. Get the http headers required from here.

  3. Paste the headers in the HTTP HEADERS tab.

  4. Copy the below text including the brackets.

    mutation UpsertPaymentRequest($input: UpsertPaymentRequestInput!){
    upsertPaymentRequest(input: $input){
      code
      message
      error
      paymentUrl
      paymentRequestId
    }
  }

  5. In the GraphQL Playground, paste it in the query/mutation section.

  6. Copy below text including brackets.

      {
    "input": {
      "referenceNumber": "<<<unique reference number here>>>",
      "amount": <<<amount (in cents)>>>,
      "type": "<<<communication type>>>",   # EMAIL / EMAIL_AND_SMS
      "email": "<<<email address of the payer>>>",
      "phoneNumber": "<<<phone number of the payer>>>",  # Only in the case of EMAIL_AND_SMS
      "invoiceRef": "<<<unique Id of the uploaded invoice>>>"
    }
  }

    NOTE: The phoneNumber field should be phone number of the payer, destination for the sms communication. Format is E.164 format, for example +14155552671.

  7. In the GraphQL Playground, open the QUERY VARIABLES tab at the bottom-left corner and paste the copied text.

  8. Now run the mutation.

  9. Once you see the response code as SUCCESS, you can get the Payment Request Id in the paymentRequestId field of the response.

    Sample SUCCESS Response:

     {
 "data": {
 "upsertPaymentRequest": {
   "code": "SUCCESS",
   "message": "payment request created",
   "error": null,
   "paymentUrl": "https://stg.payer.apteanpay.com/?MDk4NWMyMzAz...Maz=",
   "paymentRequestId": "f8aa508c-bfae-4cae-a197-21b78a92ee38"
     }
   }
 }

    Sample FAILURE Response:

     {
 "errors": [
   {
     "message": "unable to create payment request, reference number already exists",
     "locations": [
       {
         "line": 2,
         "column": 3
       }
     ],
     "path": [
       "upsertPaymentRequest"
     ],
     "extensions": {
       "code": "INTERNAL_SERVER_ERROR",
       "exception": {
         "stacktrace": [
           "Error: unable to create payment request, reference number already exists",
           "    at PaymentRequestsService.create (/services/PaymentRequestsService.js:271:19)",
           "    at runMicrotasks (<anonymous>)",
           "    at processTicksAndRejections (internal/process/task_queues.js:97:5)",
           "    at async PaymentRequestResolver.upsertPaymentRequestImpl (/gql/resolvers/PaymentRequestResolver.js:439:13)",
           "    at async PaymentRequestResolver.upsertPaymentRequest (/gql/resolvers/PaymentRequestResolver.js:470:31)",
           "    at async dispatchHandler (/node_modules/type-graphql/dist/resolvers/helpers.js:82:24)",
           "    at async /node_modules/type-graphql/dist/resolvers/helpers.js:83:26",
           "    at async dispatchHandler (/node_modules/type-graphql/dist/resolvers/helpers.js:82:24)"
         ]
       }
     }
   }
 ],
 "data": null
 }

    NOTE: In case your response code is not SUCCESS, refer below error cases.

    Error Message Error Reason
    Context creation failed: FORBIDDEN [2]: Call is forbidden "x-aptean-apim" entered is not a valid apteanpay apim key
    Context creation failed: FORBIDDEN [4]: Call is forbidden "x-aptean-tenant-secret" entered is not correct
    unable to create payment request, reference number already exists referenceNumber given already exists. It should be unique for each payment request.
    unable to create payment request, amount must be greater than $1 minimum amount to create payment request is $1(100 cents)
    unable to create payment request, uploaded invoice not found invoiceRef should be uniqueId of the uploaded invoice.
    unable to create payment request, {fieldName} is required {fieldName} is not passed in the QUERY VARIABLES
    Variable "$type" got invalid value "EMA"; Expected type CommunicationType. type should be EMAIL / NONE / SMS / EMAIL_AND_SMS
    email is required for email communications email should be passed in QUERY VARIABLES if the type is EMAIL

Upsert Payment Request No Invoice

To upsert/create a new payment request without invoice, perform the following steps.

  1. Open your browser and enter the Merchant API (GraphQL) url from here.

  2. Get the http headers required from here.

  3. Paste the headers in the HTTP HEADERS tab.

  4. Copy the below text including the brackets.

    mutation upsertPaymentRequestNoInvoice(
    $input:UpsertPaymentRequestNoInvoiceInput!)
{
  upsertPaymentRequestNoInvoice(input:$input)
  {
    code
    message
    error
    paymentRequestId
    paymentUrl
    
  }
}

  5. In the GraphQL, paste it in the query/mutation section.

  6. Copy the below text including the brackets.

    {
  "input": {
    "referenceNumber": "<<<unique reference number here>>>",
    "type": "<<<communication type>>>",      # EMAIL / EMAIL_AND_SMS
    "email": "<<<email address of the payer>>>",
    "phoneNumber": "<<<phone number of the payer>>>",  # Only in the case of EMAIL_AND_SMS
    "amount": <<<amount (in cents)>>>
  }
}

    NOTE: The phoneNumber field should be phone number of the payer, destination for the sms communication. Format is E.164 format, for example +14155552671.

  7. In the GraphQL, open the QUERY VARIABLES tab at the bottom-left corner and paste the copied text.

  8. Now run the mutation.

  9. Once you see the response code as SUCCESS, you can get the Payment Request Id in the paymentRequestId field of the response.

    Sample SUCCESS Response:

     {
   "data": {
     "upsertPaymentRequestNoInvoice": {
       "code": "SUCCESS",
       "message": "payment request created",
       "error": null,
       "paymentUrl": "https://stg.payer.apteanpay.com/?NzFjZjIwMjIwNjgzZWIwY...jE1MGIzM",
       "paymentRequestId": "cc3da344-98ba-4ddb-b707-b9426ba8c524"
     }
   }
 }

    Sample FAILURE Response:

     {
 "errors": [
   {
     "message": "unable to create payment request, amount must be greater than $1",
     "locations": [
       {
         "line": 2,
         "column": 3
       }
     ],
     "path": [
       "upsertPaymentRequestNoInvoice"
     ],
     "extensions": {
       "code": "INTERNAL_SERVER_ERROR",
       "exception": {
         "stacktrace": [
           "Error: unable to create payment request, amount must be greater than $1",
           "    at PaymentRequestsService.create (/services/PaymentRequestsService.js:242:19)",
           "    at PaymentRequestResolver.upsertPaymentRequestImpl (/gql/resolvers/PaymentRequestResolver.js:439:47)",
           "    at PaymentRequestResolver.upsertPaymentRequestNoInvoice (/gql/resolvers/PaymentRequestResolver.js:493:35)",
           "    at /node_modules/type-graphql/dist/resolvers/create.js:31:98",
           "    at runMicrotasks (<anonymous>)",
           "    at processTicksAndRejections (internal/process/task_queues.js:97:5)",
           "    at async dispatchHandler (/node_modules/type-graphql/dist/resolvers/helpers.js:82:24)",
           "    at async /node_modules/type-graphql/dist/resolvers/helpers.js:83:26",
           "    at async dispatchHandler (/node_modules/type-graphql/dist/resolvers/helpers.js:82:24)"
         ]
       }
     }
   }
 ],
 "data": null
 }

    NOTE: In case your response code is not SUCCESS, refer below error cases.

    Error Message Error Reason
    Context creation failed: FORBIDDEN [2]: Call is forbidden "x-aptean-apim" entered is not a valid apteanpay apim key
    Context creation failed: FORBIDDEN [4]: Call is forbidden "x-aptean-tenant-secret" entered is not correct
    unable to create payment request, reference number already exists referenceNumber given already exists. It should be unique for each payment request.
    unable to create payment request, amount must be greater than $1 minimum amount to create payment request is $1(100 cents)
    unable to create payment request, {fieldName} is required {fieldName} is not passed in the QUERY VARIABLES
    Variable "$type" got invalid value "EMA"; Expected type CommunicationType. type should be EMAIL / NONE / SMS / EMAIL_AND_SMS
    email is required for email communications email should be passed in QUERY VARIABLES if the type is EMAIL